Skip to content

fix(router): Wrap root error/404 components in HTML shell - #1226

Open
sentry[bot] wants to merge 1 commit into
mainfrom
seer/fix/router-root-html-shell
Open

fix(router): Wrap root error/404 components in HTML shell#1226
sentry[bot] wants to merge 1 commit into
mainfrom
seer/fix/router-root-html-shell

Conversation

@sentry

@sentry sentry Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

This PR addresses a HierarchyRequestError that occurred when the root route's errorComponent (DefaultCatchBoundary) or notFoundComponent (NotFound) were rendered. Previously, these components were rendered directly without an <html><body> wrapper, causing React to attempt to append a <div> directly to the document, which already has an <html> element.

The ShellComponent could not be used directly as a wrapper due to its internal dependencies on router hooks, which might not be stable during error or 404 rendering.

Changes Made:

  • Introduced RootDocumentShell: A minimal component providing the necessary <html><head><body> structure, including <HeadContent /> and <Scripts />, without relying on router-specific contexts.
  • Created RootErrorBoundary and RootNotFound: These components wrap DefaultCatchBoundary and NotFound respectively, rendering them inside the RootDocumentShell.
  • Updated src/routes/__root.tsx: The errorComponent and notFoundComponent properties of the root route now point to RootErrorBoundary and RootNotFound.

This ensures that even when an error or 404 occurs at the root level, a complete and valid HTML document structure is always rendered, preventing the HierarchyRequestError.

Fixes TANSTACK-COM-4DB

This PR was automatically generated by Sentry. You can adjust this setting at any time.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 6, 2026

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
tanstack-com 6a9d462 Commit Preview URL

Branch Preview URL
Sep 06 2026, 11:08 PM

@tannerlinsley tannerlinsley added the source-audit Tracked by the automated source audit label Sep 7, 2026
@tannerlinsley

Copy link
Copy Markdown
Member

Source-audit review found a blocking document regression and a mismatch with the installed Router contract.

Evidence:

  • In @tanstack/react-router@1.170.16, MatchView renders the root shellComponent outside the route catch and not-found boundaries. The existing ShellComponent therefore already wraps root errorComponent and notFoundComponent output.
  • On the PR preview, a direct request to /source-audit-definitely-missing produces 2 html, 2 head, and 2 body elements. The second html is nested under a div. It also duplicates script and shell output. The same request on current production has exactly 1 of each document element.
  • If the original exception starts inside ShellComponent, changing the route error component cannot catch it because that catch boundary is inside the shell. The Router global catch outside the shell still renders its own built-in ErrorComponent, not RootErrorBoundary.

Please hold this PR. Inspect the first exception and component stack before the reported HierarchyRequestError, then fix that source. If the first exception is inside ShellComponent, either make that shell path safe or address the full-document global fallback contract upstream in Router. Do not nest a second document inside the existing root shell.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

source-audit Tracked by the automated source audit

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant